home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / blrplt.zip / BLRPLATE.DOC < prev    next >
Text File  |  1993-04-09  |  11KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                                      April 12, 1992
  9.  
  10.                                    BoilerPlate
  11.  
  12.                  A boiler plate code generator for ObjectWindows
  13.                                    Version 1.0
  14.  
  15.  
  16.         OVERVIEW
  17.  
  18.         After writing several OWL programs,  it seemed like each time I 
  19.         started a new one, I was typing the same boiler plate code over 
  20.         again each time.  I decided that redundant stuff like this really 
  21.         ought to be handled by a program.  BoilerPlate is the result.
  22.  
  23.         Briefly, here's how it works:
  24.  
  25.           After spending some time deciding what you want in the program, 
  26.           use WRT or Resource Workshop to build a resource (.RES) file.  
  27.           It should contain your menu, icons, cursors, accelerator, and 
  28.           in the case of a TDlgWindow descendent, the dialogbox and 
  29.           controls for the main window.  The identifiers you use should 
  30.           be put in an include file for later use.
  31.  
  32.           Start BoilerPlate and read in the .RES and .INC files.  You 
  33.           then make choices for various things like program name, what 
  34.           window messages you want to handle, what OWL methods you'll be 
  35.           overriding, etc.
  36.  
  37.           BoilerPlate then writes out the source defining your main 
  38.           window object and including empty (mostly) methods for the 
  39.           menu items and window messages you selected.  The source can be 
  40.           compiled and run.  It won't do much, but you can select menu 
  41.           items, etc.
  42.  
  43.           Now all you have to do is the fun part--fill in the empty 
  44.           routines.
  45.  
  46.         Here's a summary of the code BoilerPlate generates:
  47.  
  48.           -The object type declaration for both the application and main 
  49.            window.  The main window may be a descendent of TWindow or 
  50.            TDlgWindow.  The type declaration has method headings for all 
  51.            the methods listed below.
  52.  
  53.           -Your choice of names for the application, main window, 
  54.            program, class name, and window caption.
  55.  
  56.           -Skeleton response methods for:
  57.  
  58.              *constructor, destructor, SetupWindow, GetClassName, 
  59.               GetWindowClass.
  60.  
  61.  
  62.                                    1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.              *All menu items.
  75.              *Your choice of Window messages (wm_xxxx messages).
  76.              *OWL methods you wish to override.
  77.  
  78.           -Statements for:
  79.  
  80.              *Loading your choice of icon, cursor, accelerator, and menu.
  81.              *Loading the .RES and .INC file.
  82.              *Your window style (ws_xxxx) and class style (cs_xxxx) 
  83.               selections.
  84.  
  85.           -For TDlgWindow descendents:
  86.  
  87.              *Pointers defined for dialogbox controls.
  88.              *Appropriate InitResource calls for controls.
  89.              *Response methods for control notification messages.
  90.  
  91.  
  92.         Here it is in more detail:
  93.  
  94.  
  95.         Resource File Considerations
  96.  
  97.         BoilerPlate can make use of the menu and menuitems, icons, 
  98.         accelerators, cursors, and main window dialogbox and its controls 
  99.         (TDlgWindow) in the .RES file.  It's OK to include any number of 
  100.         other resources, though.  If you don't feel like designing a 
  101.         fancy icon or cursor at this stage, do something simple--Boiler 
  102.         plate really only needs the identifier.  
  103.  
  104.         While BoilerPlate can work without any symbols, you're not 
  105.         likely to be pleased with code that's full of routines like 
  106.         '_204'.  It's most important that identifiers be provided for 
  107.         menuitems and dialogbox controls.  On the other hand, for a 
  108.         single accelerator, icon, or cursor, assigning an identifier 
  109.         isn't all that necessary.
  110.  
  111.         In some cases, BoilerPlate will slightly change your identifier 
  112.         to form a related identifier.  Here's the way it's done:
  113.  
  114.           Any underscores will be stripped from the symbol.  So, for 
  115.           instance, if you assign 'cm_Write' to a menu item, you'll end 
  116.           up a procedure 'cmWrite' to handle that menu command.
  117.  
  118.           If the identifier contains no underscores, one will be added as 
  119.           the first character so that 'cmOpen' will become '_cmOpen'.
  120.  
  121.           Finally, if no identifier is provided, the numerical value 
  122.           found in the .RES file will be used with an underscore for the 
  123.           first character.
  124.  
  125.  
  126.  
  127.  
  128.                                    2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.         Windows allows the same numerical ID to be reassigned in 
  141.         different resources so that you could have an icon, menuitem, 
  142.         and cursor all with an ID of 100, as:
  143.  
  144.           MyIcon = 100;
  145.           MyCursor = 100;
  146.           cm_Open = 100;
  147.  
  148.         But such duplicates pose a problem for BoilerPlate, since it has 
  149.         to match the numbers it finds in the .RES file with Identifiers.  
  150.         When BoilerPlate finds two or more possibilities for a match, it 
  151.         throws up a dialogbox listing the names and where it needs the 
  152.         symbol (menuitem, icon, etc) and lets the user choose.  For a 
  153.         large resource file with many duplicates this could become 
  154.         somewhat of a hassle so you might want to adopt one or more of 
  155.         the following strategies when designing your resources:
  156.  
  157.           Try to assign a different number sequence to each resource.
  158.  
  159.           Use string identifiers for menu, icon, cursor, and dialogboxes.  
  160.           There is no ambiguity with string identifiers.
  161.  
  162.           Pare down the .INC file to include only those identifiers that 
  163.           will be used by BoilerPlate.
  164.  
  165.         Once you've got the resource and include file, you're ready to 
  166.         run BoilerPlate and load the two files.  (Use 'Open' and 'Load 
  167.         symbols' in the File menu.)  Once the files are loaded, there are 
  168.         a number of dialogboxes to 'visit' where you can make various 
  169.         choices.  As you OK each dialog, its location on the menu gets 
  170.         checked and after all are checked, you then write the source 
  171.         code.
  172.  
  173.         The dialogs are described somewhat briefly below.  However, each 
  174.         dialogbox has a Help button which will bring up additional 
  175.         information.
  176.  
  177.  
  178.         Names Dialog
  179.  
  180.         In the Names dialog, you choose your program name, main window 
  181.         name, application name, class name, and main window caption.  
  182.         In the case of window and application names, BoilerPlate will 
  183.         add a preceding 'T'.  Hence if you choose 'MyWindow' for a window 
  184.         name, it will appear in the program as TMyWindow and have a 
  185.         pointer name of PMyWindow.
  186.  
  187.         In this dialog, you also choose whether your main window will be 
  188.         a descendent of TWindow or TDlgWindow.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                    3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.         Styles/Window Styles  (TWindow only)
  207.  
  208.         Here you choose the ws_xxxx window styles.  The selection 
  209.         possibilities are shown in the left listbox and the choices in the 
  210.         right listbox.  To add a ws_ style, select it and push the 'Add' 
  211.         button (or double click on the selection).  Removing a selection 
  212.         from the right listbox is done in a similar manner using the 
  213.         'Delete' button.
  214.  
  215.         Note that ws_OverlappedWindow is a combination of a number of 
  216.         other selections which will appear individually in the right 
  217.         listbox.  The 'Result' window shows the selections reorganized as 
  218.         they will be inserted in the source.
  219.  
  220.  
  221.         Styles/Class Styles
  222.  
  223.         The choice of cs_xxxx styles are made here in a similar manner.
  224.  
  225.  
  226.         Resources/Menu Accelerator
  227.  
  228.         If there is more than one menu or accelerator in your resource 
  229.         file, you can make the choice for the main window here.
  230.  
  231.  
  232.         Resources/Icon Cursor
  233.  
  234.         Here you can choose from among the cursors and icons defined 
  235.         within your resource file as well as windows standard icons and 
  236.         cursors.  You can also type in an identifier for an icon/cursor 
  237.         to be designed later.
  238.  
  239.  
  240.         Methods/Window Messages
  241.  
  242.         The listbox on the left contains possible window wm_xxxx messages 
  243.         from which you can select to handle within your program.  Only 
  244.         the more common messages are listed but you can type in any other 
  245.         messages if necessary.
  246.  
  247.  
  248.         Methods/Other Methods
  249.  
  250.         Here you can select from a list of standard OWL procedures which 
  251.         you may need to override.  You can also enter other special 
  252.         methods you may need.  When entering your own methods, you should 
  253.         include the parameter list if applicable.
  254.  
  255.  
  256.         Once you've made all the necessary selections, you then choose 
  257.         'Write source' from the File menu to output the Pascal source 
  258.  
  259.  
  260.                                    4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.         code.  Barring a few things that can go wrong like selecting a 
  273.         conflicting symbol, the code should compile and run.
  274.  
  275.  
  276.         TDlgWindow Descendants--Special Considerations.
  277.  
  278.         If your main window is going to contain dialogbox controls such 
  279.         as edit boxes, listboxes, buttons, you should consider making it 
  280.         a descendent of TDlgWindow rather that TWindow.  It's a lot 
  281.         easier to lay out controls in the resource editor than it is to 
  282.         guess at positions and sizes.  You save some coding too.
  283.  
  284.         Here's a couple of points regarding TDlgWindow descendents:
  285.  
  286.           When you design your main window dialog, make sure you give it 
  287.           a class name.  Enter the same class name in the BoilerPlate's 
  288.           Names dialog.  (Actually, BoilerPlate will pick up the name 
  289.           when you select the main window dialog.)
  290.  
  291.           A menu is optional.  The menu is designed in the usual way, but 
  292.           its identifier is assigned to the dialog in the dialogbox 
  293.           editor.
  294.  
  295.  
  296.  
  297.         COPYRIGHT
  298.  
  299.                 (C) Copyright 1992 by L. David Baldwin.
  300.                           All Rights Reserved
  301.  
  302.         BoilerPlate may be copied and distributed freely providing that 
  303.         no fee is charged and it is not part of a package for which a 
  304.         charge is made.
  305.  
  306.         Source code for BoilerPlate is available for $20 (need not be 
  307.         sent in advance).  Also please report any problems, suggestions, 
  308.         etc.
  309.  
  310.         Contact me by Compuserve (the best way) or at one of the 
  311.         addresses below.
  312.  
  313.         Dave Baldwin
  314.         CompuServe ID #76327,53.
  315.  
  316.              22 Fox Den Rd., (Summer)     144 13th St. East,  (Winter)
  317.              Hollis, NH 03049             Tierra Verde, FL 33715
  318.              (603) 465-7857               (813) 867-3030
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                    5
  327.  
  328.  
  329.  
  330.  
  331.